Crate seeded_dice_roller

Seeded Dice Roller

SeededDiceRoller is, as its name implies, a dice roller using a seed to give pseudo-random deterministic results.

In other words, it returns “random” results, which will always be the same if you use the same seed and call the same methods in the same order.

How does it work

You generate a Dice Roller using a seed, then you can use it to make dice rolls, generate random numbers or booleans, or select a specific result in an array of possible choices using either a predefined dice roll, a gaussian distribution or a simple pick at random.

It is also possible to give weight to the various choices in order to multiply their chances to be selected.

Seed

The seed is split into two parts, the seed proper and a “step”. The seed represents something like the “session” of the run, while the step represents the name of the task currently at hand. The idea is to keep seeded generation consistent between versions of your program.

For example, if we want to generate a dungeon using the player-inputted seed “water temple”, we might create three specific instances of SeededDiceRoller using “map_gen_shape”, “map_gen_walls” and “map_gen_treasures” values for the step in order to always get the same results for those specific tasks, no matter how many other tasks you might add or remove before them in the future.

Examples

Dice rolls

	let mut rng = SeededDiceRoller::new("seed", "step");

    assert_eq!(rng.roll(1, 6, 0), 6);
    assert_eq!(rng.roll(3, 6, -5), 1);
    assert_eq!(rng.roll(3, 6, -5), 8);

Random picks

Picks a result using a predefined roll type

	let mut rng = seeded_dice_roller::SeededDiceRoller::new("seed", "step");

	let possible_results = SeededDiceRoller::to_copyable_possible_results(vec![
	    "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k"
	]);
    let result = rng.get_result(&CopyableRollToProcess {
                                    possible_results: possible_results.clone(),
                                    roll_method: RollMethod::PreparedRoll(PreparedRoll {
                                        dice: 2,
                                        die_type: 6,
                                        modifier: 0
                                    }),
                                }).unwrap();

    assert_eq!(result, "g");

Picks a result with higher chances to get one from the middle of the array

	let mut rng = seeded_dice_roller::SeededDiceRoller::new("seed", "step");

	let possible_results = SeededDiceRoller::to_copyable_possible_results(vec![
	    "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k"
	]);
    let result = rng.get_result(&CopyableRollToProcess {
                                    possible_results: possible_results.clone(),
                                    roll_method: RollMethod::GaussianRoll(5),
                                }).unwrap();

    assert_eq!(result, "e");

Picks a result randomly, each choice has an equal chance to be selected

	let mut rng = seeded_dice_roller::SeededDiceRoller::new("seed", "step");

	let possible_results = SeededDiceRoller::to_copyable_possible_results(vec![
	    "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k"
	]);
    let result = rng.get_result(&CopyableRollToProcess {
                                    possible_results: possible_results.clone(),
                                    roll_method: RollMethod::SimpleRoll,
                                }).unwrap();

    assert_eq!(result, "c");

Picks a result randomly, “a” is 5 times more likely to be selected than “b” or “c”

	let mut rng = seeded_dice_roller::SeededDiceRoller::new("seed", "step");

    let weighted_set = vec![
        CopyableWeightedResult { result: "a", weight: 5 },
        CopyableWeightedResult { result: "b", weight: 1 },
        CopyableWeightedResult { result: "c", weight: 1 },
    ];
    let result = rng.get_result(&CopyableRollToProcess {
                                    possible_results: weighted_set,
                                    roll_method: RollMethod::SimpleRoll,
                                }).unwrap();

    assert_eq!(result, "c");

Structs

• CopyableRollToProcess
  Data allowing to pick a result at random in a list of possible results. The results must be copyable.
• CopyableWeightedResult
  A result able to be picked at random in a list of possible results. The weight is used to determine the chances of this result to be picked against all other possible choices. The result must be copyable.
• PreparedRoll
  Data allowing to roll dice times a die_type sided die and add an eventual modifier.
• RollToProcess
  Data allowing to pick a result at random in a list of possible results.
• SeededDiceRoller
  Uses a Random Number Generator fed with a seed to generate dice roll results, booleans and numbers in a deterministic way.
• WeightedResult
  A result able to be picked at random in a list of possible results. The weight is used to determine the chances of this result to be picked against all other possible choices.

Enums

• RollMethod
  Enum used to know how to determine the result of a random pick in a list of possible results.